home *** CD-ROM | disk | FTP | other *** search
/ Toolkit for Duke Nukem 3D / Walnut Creek CDROM - Toolkit for Duke Nukem 3D.iso / tutorial / conhack.txt < prev    next >
Text File  |  1996-07-22  |  31KB  |  875 lines

  1. THE UNOFFICIAL DUKE NUKEM 3D .CON FILE HACKER'S GUIDE (v .025)
  2. By Ben Cantrick (cantrick@rintintin.colorado.edu)
  3.  
  4. Obnoxious but possible important mumbo-jumbo:
  5.  
  6.   This document is perpetually under revision. Please e-mail corrections,
  7. comments, additions, clarifications, etc... to the author! In particular,
  8. I'd love info and WELL COMMENTED example code for AI routines and anything
  9. else you can think of related to .CON file hacking.
  10.  
  11.   All permissions are given to copy and reproduce this document provided
  12. no profit is made from such. The author disclaims all responsibility
  13. for the information contained herein and makes no express or implied
  14. warranty for it's fitness for any particular use. If playing with your
  15. .CON files makes your computer crash, it's not my fault!
  16.  
  17.  
  18. -----
  19.  
  20. What's new since version .021?
  21.  
  22.   - Restructuring of the primitives and "where to find" sections.
  23.   - Restructuring of the thank you's section.
  24.   - Some primitives clarified.
  25.   - New primitive discovered. (operate)
  26.   - Yet another web page added.
  27.   - No more examples yet. (Argh!)
  28.  
  29. -----
  30.  
  31.  
  32. INDEX/TABLE OF CONTENTS:
  33.  
  34.   A. What are .CON files?
  35.   B. Can I alter .CON files?
  36.   C. How do I alter .CON files?
  37.     * What is all this strange C-programming language-like junk?
  38.      ***** DEFS.CON: define
  39.      ***** USER.CON: definequote, definelevelname, music, definesound
  40.      ***** GAME.CON: comments, include, primitives
  41.       - Listing of primitives + their uses (if known)
  42.   D. Examples
  43.     * Trampoline trash cans
  44.     * Hollow-point pistol bullets    (Unfinished)
  45.     * Kamikaze enemies            (Unfinished)
  46.   E. So now what?
  47.   F. Appendix
  48.     * Where can I get this document?
  49.     * Contributors/Thank You's.
  50.  
  51. -----
  52.  
  53.  
  54. A. What are Duke Nukem 3D .CON files?
  55.  
  56.   .CON files are text files that "CON"trol certain aspects of the DOOM-
  57. like game Duke Nukem 3D (DN3D). There are three of them that come with
  58. the Shareware version of DN3D: DEFS.CON, USER.CON, and GAME.CON. (The full
  59. version of DN3D is has not been released as of the writing of this
  60. document, and so I can't say anything about it.) When DN3D starts up,
  61. it loads GAME.CON, checks it for errors, and if there are none keeps the
  62. instructions contained in it for use later on in the game. (GAME.CON is
  63. in charge of loading up any supplemental files, like DEFS.CON and USER.CON,
  64. that it may want to use) The instructions currently known to be usable in
  65. GAME.CON control things as mundane as how much damage each kind of weapon
  66. does to things as exotic as how enemies behave.
  67.  
  68.  
  69.  
  70. B. Can I alter .CON files?
  71.  
  72.   Yes, you most certanly can. This is one of the nicer features of the
  73. Build engine, or at least Duke3D's implementation of the Build Engine.
  74.  
  75.  But, before you start playing with them, you should definitly MAKE A
  76. BACKUP OF ALL YOUR .CON FILES!!!!! This is not only to prevent you from
  77. having to re-install DN3D if you mess up your existing .CON files, but
  78. also so that you can have the original .CON files as reference material
  79. when you start altering them. Once you've got backups made, altering
  80. the .CON files couldn't be easier: just open them up with your favorite
  81. text editor and edit away.
  82.  
  83.  
  84.  
  85. C. How do I alter .CON files?
  86.  
  87.   * What does all this weird, C-like junk in my .CON files mean??
  88.  
  89.   A lot of things, depending on which .CON file you edited. Let's take
  90. the .CON files from least complex to most complex:
  91.  
  92.  
  93.   ***** DEFS.CON:
  94.  
  95.   Most of the lines in DEFS.CON look something like:
  96.  
  97.     define SOMETHING SOMENUMBER
  98.  
  99.   What they do is basically simple substitution: If you have a line
  100. somewhere in your DEFS.CON that said:
  101.  
  102.     define THEANSWER 42
  103.  
  104.   Then any time after that, if the word "THEANSWER" appears, "42" is
  105. substituted in it's place.
  106.  
  107.   By themselves, these lines aren't very interesting. They become helpful
  108. later on, when you're writing actor code and don't want to remember that
  109. an enemy who is TOUGH happens to have a strength of 137. You can just:
  110.  
  111.     define TOUGH 137
  112.  
  113.   And thereafter don't have to remember that TOUGH = 137, you just know
  114. that an enemy is TOUGH.
  115.  
  116.   Defines are ubiquitous; almost everything in the .CON files is really a
  117. number, but is DEFINEd to be a name so it makes more sense. At some point
  118. you can just stop caring whether things are DEFINEd labels or numbers, but
  119. be aware that most of the things you deal with are really numbers.
  120.  
  121.  
  122.  ***** USER.CON:
  123.  
  124.   USER.CON is somewhat like DEFS.CON in that it mostly just defines things.
  125. However, USER.CON usually defines things that might be interesting to the
  126. game player, whereas DEFS.CON usually defines things that a DN3D player
  127. could care less about. USER.CON also contains nice technical notes written
  128. by the 3D Realms .CON programmer, Tod Replogle, that tell you all about how
  129. to modify it. Almost all of the info below is basically a rehash of the notes
  130. you can find in USER.CON
  131.  
  132.   There are 5 major kinds of lines in USER.CON: defines, definequotes,
  133. definelevelnames, musics and definesounds.
  134.  
  135.   "define" lines are no different than they were in DEFS.CON; they define
  136. stuff. Most of the stuff you can define here is emminantly useful, tho.
  137. Examples abound: You can define Duke's starting and maximum health and
  138. armor values here. You can define how much ammo Duke gets per clip picked up,
  139. how much ammo is allowed for each weapon, how much damage each weapon does
  140. per hit, etc, etc...
  141.  
  142.  
  143.   "definequote" lines define the different things that will pop up on the
  144. screen in response to certain game events. You can define what words
  145. appear on the screen when you get an some ammo or an inventory item, what
  146. words appear on the screen when you use the various cheat codes, what
  147. words will appear when you adjust game options, etc, etc...
  148.  
  149.  "definequote" lines have two arguments: a number and a quote. The number
  150. is what you use to refer to the quote by later on. For example, the line:
  151.  
  152.     definequote 101     NIGHT VISION GOGGLES!
  153.  
  154.  Defines quote number 101 is "NIGHT VISION GOGGLES!" (This is pretty
  155. obvious, isn't it?) One other thing to keep in mind while making quotes;
  156. Todd Replogle, the Duke3D .CON file programmer, cautions:
  157.  
  158. >// Maximum quote size is 64 characters.
  159.  
  160.  
  161.   "definelevelname" lines are used to define the episode and level number,
  162. floor-plan file, par and record times, and level names for each level. The
  163. format of a definelevelname line is:
  164.  
  165.     definelevelname #LEVEL #EPSIODE MAPFILE PARTIME RECORDTIME LEVELNAME
  166.  
  167.   For example, Episode 1, Level 5 is "The Abyss." The floor-plan of this
  168. level is in the file E1L5.map. (which is actually contained in DUKE3D.GRP)
  169. The par time is 9 minutes, 10 seconds, and the record time is 5 minutes
  170. flat. It's definelevelname entry looks like this:
  171.  
  172.     definelevelname 0 4 E1L5.map 09:10 05:00 THE ABYSS
  173.  
  174.   As you can see, you must subtract one from the actual episode and level
  175. numbers before you put them on the definelevelname line. We're in Episode 1,
  176. but the #EPISODE is 0. We're in level 5, but the #LEVEL is 4. Notice also
  177. that you should (I don't think it's actually required) pad the par and
  178. record times with a leading 0 if necessary. There are also some comments
  179. from Todd Replogle, taken from USER.CON:
  180.  
  181. >  - Level file names cannot excede 13 characters.
  182. >  - Level par cannot excede 5 characters (min:sec)
  183. >  - Level titles cannot excede 32 characters.
  184.  
  185.  
  186.   "music" lines (as far as I can tell) define which .MID files to play for
  187. each level. Beyond that I'm not entirely sure how "music" lines specify
  188. exactally which file to play for which level; if someone can enlighten
  189. me I'd be appreciative.
  190.  
  191.  
  192.   "definesound" lines define various names that correspond to ways to
  193. play a VOC file. The format of a definesound line is:
  194.  
  195.     definesound SOUNDNAME VOCFILENAME.voc    #1  #2  #3  #4  #5
  196.  
  197.   Once again, Todd Replogle has provided .CON file hackers with a helpful
  198. technical note in USER.CON:
  199.  
  200. >    -----------------------------------------------------------------
  201. >    ABOUT CHANGING SOUND FX
  202. >    The sound fx section follows this explanation.
  203. >
  204. >    1. The program expects to find a .VOC file
  205. >    2. You can either change the VOC name listed below to match your new
  206. >       sound, or you can rename your file to match the name here.
  207. >    3. New sound files should be added to the game directory.  Though
  208. >       all sound files shipped with the game are included inside the
  209. >       .GRP file, the program will know if there are sound files outside
  210. >       the .GRP file, and will use them instead.
  211. >    4. The numbers that are to the right of the sound file name are
  212. >           technical parameters which will not be explained here, except as
  213. >           follows...
  214. >       - The first 2 numbers define a random pitch variation range.
  215. >             They can be positive or negative numbers.
  216. >       - The 3rd number is a priority flag.
  217. >       - The 4th number is a bit parsed set of technical variables
  218. >             that identify the type of sound it is in the game.
  219. >       - The 5th number is a volume adjustment flag.
  220. >    -----------------------------------------------------------------
  221.  
  222.   The explanation seems pretty self-evident, so I won't go into a detailed
  223. explanation of each field of the definesound line.
  224.  
  225.  
  226.  
  227.  ***** GAME.CON:
  228.  
  229.   The BIGGIE! Lots of stuff in this one, and most of it rather difficult to
  230. explain... let's start out with the first couple of lines, which are:
  231.  
  232.     /*
  233.     -------------------------------------------------------------------
  234.         Duke Nukem 3D Script Code.
  235.     Todd Replogle.
  236.     -------------------------------------------------------------------
  237.         */
  238.  
  239.   If you're a C programmer, this stuff is immediatly obvious: everything
  240. between /* and */ is considered a "comment" and Duke3D will almost always
  241. ignore it when reading in GAME.CON. (I say "almost always" because it appears
  242. that Duke still counts the curly braces, { and }, inside comments. This can
  243. lead to some interesting effects; comment out some bad code that has non-
  244. matching curly braces and the game might refuse to load up, even though the
  245. bad code is inside a comment, and supposedly never even seen.)
  246.  
  247.   There are two kinds of comments: the double-slash or "//" comment and the
  248. "/* */" comment. A "//" comment starts at the double-slash and extends to the
  249. end of the line. A "//" comment ends at the end of the line.
  250.  
  251.   The "/* */" comment can span several lines, but "//" comments only "null
  252. out" one line, at most. Many // and /* */ comments can be found all over
  253. DEFS.CON, USER.CON, and GAME.CON.
  254.  
  255.   Forewarned: you must put a space after "//" before typing the text of
  256. the comment. The comment: "//This is a comment" will cause Duke3D to error
  257. out. Changing the comment to "// This is a comment" will fix the problem.
  258. I assume the same holds for "/* */" comments. Things like: "/*C*/" are
  259. a no-no. Things like "/* C */" are OK.
  260.  
  261.  
  262.   The next few lines in GAME.CON are "include" lines which basically
  263. cause Duke3D to process the specified file. The line:
  264.  
  265.     include defs.con
  266.  
  267.   Makes DN3D go process DEFS.CON before it moves along to the next line.
  268.  
  269.  
  270.   And now, the really big, confusing ones: states, actions, and actors.
  271.  
  272.   Apogee hasn't said anything about states, actions, or actors yet, so the
  273. things I'm about to tell you are pure conjecture based on observation and
  274. experimentation:
  275.  
  276.  
  277.   *****STATEs
  278.  
  279.   As far as I can tell, "states" can be thought of as something like
  280. subroutines. You go into a state, do something, and then come back to
  281. wherever you were. The first state in GAME.CON is the "rats" state, which
  282. randomly makes some rats whenever it's called.
  283.  
  284.   The format of a state is:
  285.  
  286. state #STATENAME
  287.  ...
  288. ends
  289.  
  290.   STATENAME is a unique number that is usually DEFINEd to be the name of
  291. the state. No two states should have the same number. "ends," of course,
  292. is short for "End State." Be sure that your states are defined before you
  293. try and use them. If you try and use a state (in an actor, perhaps) that
  294. hasn't been defined earlier in the file, DN3D will error.
  295.  
  296.  
  297.   *****ACTIONs
  298.  
  299.   As far as I can tell, an "action" specifies a sequence of sprites
  300. (pictures) to draw onto the screen. The format of an action is still
  301. not quite entirely known, but it seems to be something like this:
  302.  
  303.     action #SPRITEGROUP #FIRSTFRAME #LASTFRAME #?? #?? #DELAY
  304.  
  305.   Each action has a set of pictures, or "frames" associated with it.
  306. The number first number, #SPRITEGROUP, defines this bunch of picures, or
  307. a "sprite group." #SPRITEGROUP is usually a DEFINEd number, so you can
  308. type "action BURNING_FRAMES" instead of having to remember that the fire
  309. animation frames are number 327, and typing "action 327." The second and
  310. third numbers of an action specify which sequence of frames from the
  311. specified sprite group group to step through when you're animating this
  312. sprite. (Animation starts from the whatever-th frame in the sprite group,
  313. number #FIRST, and goes until the whatever-th frame in the group, number
  314. #LAST. Then it usually loops back to the first frame or else quits,
  315. depending on the actor code controlling it.)
  316.  
  317.  The #DELAY number determines the delay between frame changes. That is,
  318. how rapidly the frames are animated on-screen. 1 = small delay and fast
  319. animation, bigger numbers = bigger delays and slower animation. (I think?)
  320.  
  321.  The two remaining numbers are a mystery. If anybody knows what they mean
  322. and how they're used, please mail me at cantrick@rintintin.colorado.edu so
  323. I can add them to the guide.
  324.  
  325.  
  326.   *****ACTORs
  327.  
  328.   As far as I can tell, an "actor" is any (freestanding?) object in the
  329. game that does something. Obviously, Duke and the enemies are actors.
  330. However, the rubber-maid trash cans in the movie-theater lobby are also
  331. actors, because they dent and then bounce back when you shoot them. The
  332. items and weapons and clips are also actors, because they also do something
  333. when you run over them: they give you an item, a weapon, or more ammo.
  334.  
  335.   Walls are not actors, because they don't 'do' anything except sit there.
  336. (Bullet-holes being an exception, I guess. Perhaps the bullets themseves are
  337. some kind of actor that effect the surface they hit.) Doors and lifts are
  338. borderline; I suppose the game might treat them as actors internally, but I
  339. don't know if you can/how you would alter their behavior in the .CON file.
  340.  
  341.   The format of an actor is something like:
  342.  
  343.     actor #ACTORNUMBER #ACTORSTRENGTH #ACTION #SPEED #AI_FUNCTION
  344.      ...
  345.     enda
  346.  
  347.   #ACTORNUMBER is (I think?) a unique number that identifies this actor.
  348. No two actors should have the same number. Usually #ACTORNUMBER is
  349. DEFINEd to be something easier to remember than a number.
  350.  
  351.   #ACTORSTRENGTH is a number that determines how much damage this actor
  352. can take before it breaks, dies, etc... (I think?) Putting a value of 0
  353. for this field makes the object invincible. Usually, #ACTORSTRENGTH is
  354. DEFINEd to be something easy to remember. (See 'define TOUGH' above.)
  355.  
  356.   #ACTION is (I think?) the number of an action (that is, the identifying
  357. number of a series of frames) to cycle through for this actor, if this
  358. actor is animated. Patches of fire actors use this to maintian an image-
  359. loop so they look like they're constantly burning. The HoloDuke recharge
  360. also uses an action to make the shimmer propagate across it's surface.
  361.  
  362.   #SPEED is (I think?) how fast this actor moves, if it moves. I don't know
  363. if "move" is always interpreted in the traditional sense; it appears from
  364. the gun-turret actor code that turrets that spin in place are considered to
  365. be "moving."
  366.  
  367.   #AI_FUNCTION is (I think?) a number, as defined in DEFS.CON, that
  368. specifies what this actor's initial AI is if it has an initial AI. The AI
  369. routines are: face_player (1), geth (2), getv (4), random_angle (8),
  370. face_player_smart (64), fleeenemy (128), seekplayer (512), fleeplayer (1024),
  371. looking (2048) and dodgebullet (4096). As to what these mean or how they
  372. work, I haven't any idea.
  373.  
  374.   The last three parameters of actor seem to be optional. Things that aren't
  375. animated, don't "move" and have no AI don't seem to include those parameters.
  376. You can make a perfectly sensible actor without them; as a matter of fact
  377. the majority of non-enemy actors in Duke3D (ammo and items) do not use them
  378. at all.
  379.  
  380.  
  381. * You keep putting "..." inside states and actors as if we already know
  382.   what's supposed to go inside there; but we don't!
  383.  
  384.   Well, this is kind of sticky; there are quite a few things inside there,
  385. most of them vaguely reminiscent of the C programming language with a
  386. virtual environment twist. The things that go inside actors and actually
  387. make up the actor "code" are what I'll call "primitives." Primitives are
  388. simple operations that the Build Engine will perform for you. For instance,
  389. one primitive is "ifrnd" which will tell you if a random number between
  390. 0 and 256 was less than the number you gave it. For instance, if you
  391. wanted there to be a 1 in 2 chance of something happening, you could put:
  392.  
  393.  ifrnd 128 {
  394.   ...        // 50% chance that this stuff gets done.
  395.  }
  396.  
  397.   Since 128 is half of 256, the random number between 0 and 256 will be
  398. less than 128 about half the time. Thusly, the "..." inside that
  399. "ifrnd" block will only be executed about half the times the ifrnd is
  400. run. To take another example: if you wanted a 1/4 chance, you'd
  401. ifrnd 64 { ... }. Since a random number between 1 and 256 will be less
  402. than 64 about 25% of the time.
  403.  
  404.   There are a bunch of other primitives, too. I'll list them each here,
  405. along with their arguments and what they do. After that, I'll give some
  406. (hopefully) illustrative examples on how to use them.
  407.  
  408.   Note: Primitives marked with a "?" instead of a "-" are still mysteries
  409. to me. As usual, mail me (cantrick@rintintin.colorado.edu) if you know how
  410. they work or if I've forgotten any primitives.
  411.  
  412.   Note: Most "add" primitives are subject to some kind of limit. These
  413. limits are usually explained in the explanation of the primitive.
  414.  
  415.  Note: All (?) 'ifXXXXX' primitives can have an (optional) else clause
  416. that gets executed if the condition being tested is false. For instance:
  417.  
  418.     ifphealthl 45 {
  419.       quote OK              // Print "You're OK."
  420.     }
  421.     else {
  422.       quote BUMMER          // Print "Find some health!"
  423.     }
  424.  
  425.  
  426.  *****PRIMITIVES:
  427.  
  428. addammo #WEAPON #AMT            - Adds #AMT ammo to #WEAPON weapon,
  429.                                         Subject to max ammo constraint for
  430.     that weapon. Does not give player #WEAPON, only gives them ammo.
  431.     Ex: "addammo PISTOL_WEAPON PISTOLAMMOAMOUNT"
  432.  
  433.  
  434. addinventory #ITEM #AMT            - Adds #AMT of #ITEM to player's
  435.                     inventory, subject to #ITEM's max
  436.     amount limit.
  437.  
  438.  
  439. addkills #NUM                - Adds #NUM to number of kills
  440.                     player has made.
  441.  
  442.  
  443. addphealth #NUM                - Adds #NUM points to player's
  444.                     health. (#NUM may be negative.)
  445.  
  446.  
  447. addweapon #WEAPON #INITIALAMT        - Gives player weapon #WEAPON that
  448.                     has #INITIALAMT of ammo in it.
  449.     Ex: "addweapon SHOTGUN_WEAPON 10"
  450.  
  451.  
  452. ai AINAME #ACTION #SPEED #AITYPE    ? Defines an AI routine for enemies
  453.                     to use. AINAME is any string,
  454.     #ACTION is the series of frames to cycle through when the enemy
  455.     is using this AI, #SPEED is how fast the enemy moves when using this
  456.     AI and #AITYPE is what the enemy does when it's using this AI. (For
  457.     a list of AITYPEs, see #AI_FUNCTION under ACTORs.)
  458.  
  459.  
  460. break                    - Stops whatever you're doing and
  461.                     immediatly exits the currently
  462.     running actor or state.
  463.  
  464.  
  465. cactor #ACTORNUM            ? As far as I can tell, this
  466.                     primitive "c"alls another "actor"
  467.     to do something for you.
  468.  
  469.  
  470. cstat #NUM                ? Allows setting of the attribute
  471.                     bit(s) of the current actor. #NUM
  472.     is the sum of the attributes you want this object to have. The values
  473.     of the attributes are as follows:
  474.  
  475.         1 - ?
  476.         2 - Translucent (With black as the transparent color?)
  477.         4 - Moving?
  478.         8 - Upside-Down
  479.         16 - Background (If looked at from above, this object
  480.     will appear blended in with the background.  Viewed any other way,
  481.     it will look normal.)
  482.         32 - Floor Texture (Draws object as a flat square on the
  483.     ground)
  484.         64 - ?
  485.         128 - Half submerged (Maybe for floating things?)
  486.         256 - Solid. (You can shoot it, you can stand on it, etc...)
  487.         32768 - Invisible.
  488.  
  489.     Ex. "cstat 10     // Turn upside-down and translucent. (10 = 8 + 2)"
  490.  
  491.  
  492. debris #??? #AMT            - Causes some debris to fly. (Whose
  493.                         action or spritegroup is defined
  494.     by #??? ?). Larger values of #AMT make more junk fly. Acceptable
  495.     values of #??? seem to be "SCRAP1" and "SCRAP2."
  496.     Ex. "debris SCRAP2 5  // Lots!"
  497.  
  498.  
  499. define                     - Defines various things. See other
  500. definesound                sections of document.
  501. definelevelname
  502.  
  503.  
  504. fall                    - Causes the current actor to "fall"
  505.     until it hits a surface it can come to rest on. Good to do right after
  506.     you "spawn" something small from inside something larger.
  507.  
  508.  
  509. globalsound #SOUND             ? Plays the sound associated with
  510.                     #SOUND at (which?) Duke's location.
  511.  
  512.  
  513. guts #??? #AMT                - Like debris, but causes different
  514.                     kinds of body parts to fly instead
  515.     of debris. Acceptable values for #??? seem to be JIBS1 to JIBS5 (Misc
  516.     body parts) as well as HEADJIB1, LEGJIB1, ARMJIB1 (Trooper parts),
  517.     LIZMANARM1 and LIZMANLEG1 (Captain).  Also DUKETORSO, DUKELEG and
  518.     DUKEGUN.  Ex. "guts JIBS1 1   // A spine."
  519.  
  520.  
  521. hitradius #RADIUS #1 #2 #3 #4        ? Defines the effective distance and
  522.                     strenghts of area-effectors like
  523.     explosions and fires. #RADIUS determines the circle of maximum
  524.     effect, (I think?) within which damage done to objects is given by
  525.     #4.(?) Objects farther away (how much farther?) from the center of
  526.     effect suffer damages of #3, objects farther than that sustain damage
  527.     #2, objects farther yet take damage equal to #1, and objects
  528.     sufficiently far away from the area-effector suffer no damage at all.
  529.     Ex: "hitradius 1024 WEAKEST WEAK MEDIUMSTRENGTH TOUGH"
  530.  
  531.  
  532. ifactor    #NUM                ? Tells you if the currently
  533.                     executing code was called by
  534.     the given actor?
  535.  
  536.  
  537. ifactornotstayput            ?
  538.  
  539.  
  540. ifaction #ACTION { ... }        - Tests if the current actor is
  541.                     executing the given action, and
  542.     executes the appropriate code.
  543.  
  544.  
  545. ifactioncount #NUM { ... }        - Tests if the current actor is
  546.                               displaying the given frame of an
  547.     action, and exectes the appropriate code.
  548.  
  549.  
  550. ifbulletnear                ? Checks to see if a bullet has
  551.                     passed near the current actor?
  552.  
  553.  
  554. ifcansee                - Returns true if Duke can
  555.                     see the current actor.
  556.  
  557.  
  558. ifcanseetarget                ? Enemy AI routine?
  559.  
  560.  
  561. ifcanshoottarget            ? Enemy AI routine?
  562.  
  563.  
  564. ifceilingdistg #NUM             - Returns true if the distance to
  565. ifceilingdistl #NUM            the ceiling is greater/less than
  566.                     the given number.
  567.  
  568.  
  569. ifcount                    ? Like ifactioncount, but counts
  570.                     the number of frames total that
  571.     have been used since the last call to ifcount?
  572.  
  573.  
  574. ifdead                    - True if the current actor has
  575.                     taken as much damage as they can
  576.     given their strength and should be pushing up daisies.
  577.  
  578.  
  579. iffloordistg #NUM            - True if the distance from the
  580. iffloordistl #NUM            current actor to the floor is
  581.                     greater/less than #NUM.
  582.  
  583.  
  584. ifgapzl    #NUM                ? True if the distance between the
  585.                     floor and the ceiling at the actor's
  586.     location is less than #NUM.
  587.  
  588.  
  589. ifhitweapon                ? True if the current actor was
  590.                     hit with a weapon recently. (How
  591.     recently? Since the last call to ifhitweapon?)
  592.  
  593.  
  594. ifinwater                - True if the current actor is
  595. ifonwater                in/on water.
  596.  
  597.  
  598. ifmove #NUM                ? True if the value of variable
  599.                     #NUM is not false?
  600.  
  601.  
  602. ifnotmoving                ? True if the current actor is
  603.                     not moving?
  604.  
  605.  
  606. ifp #COND                ? True if a player (the last one
  607.                     that affected this actor?) satisfies
  608.     #COND, when #COND can be one of the defined (in DEFS.CON) numbers:
  609.     pstanding, pwalking, prunning, pducking, pfalling, pjumping,
  610.     phigher, pwalkingback, prunningback, pkicking, pshrunk, pjetpack,
  611.     ponsteroids, ponground, palive, pdead, pfacing.
  612.  
  613.  
  614. ifpdistg #NUM                ? True if a(?) player's distance
  615. ifpdistl #NUM                from the current actor is greater/
  616.                     less than #NUM.
  617.  
  618.  
  619. ifphealthg #NUM                ? True if (which?) player's health
  620. ifphealthl #NUM                is greater/less than #NUM.
  621.  
  622.  
  623. ifpinventory #ITEM #AMT            ? True if less than #AMT of #ITEM
  624.                     is in (which?) player's inventory.
  625.  
  626.  
  627. ifrespawn                - True if monsters should respawn.
  628.  
  629.  
  630. ifrnd #NUM                - True if #NUM is less than a
  631.                     randomly selected number between
  632.     0 and 256. Ex. "ifrnd 128 {...}        // 50% chance."
  633.  
  634.  
  635. ifhitspace                ? True if a(?) player hit space.
  636.  
  637.  
  638. ifplayersg #NUM                ? True if (which?) player has
  639. ifplayersl #NUM                greater/less than #NUM Dukes left.
  640.  
  641.  
  642. ifspawnedby #ACTOR            - True if the current actor was
  643.                     SPAWNed by the given type of actor.
  644.  
  645.  
  646. ifspritepal #NUM            ? True if the current actor's
  647.                     sprite palette is #NUM. (See
  648.     spritepal for a listing of palette numbers and their meanings.)
  649.  
  650.  
  651. ifsquished                ? True if the current actor was
  652.                     hit by the shrink ray and then
  653.     stepped on. Ex. "ifsquished sound SPLURT    // Yummy!"
  654.  
  655.  
  656. ifwasweapon #WEAPON            ? True if the current actor was
  657.                     recently(how recently?) hit by a
  658.     shot from weapon corresponding to #WEAPON.
  659.  
  660.  
  661. killit                    - Removes the current actor from
  662.                     the map. Seems to need to be the
  663.     last instruction executed in an actor. In particular, don't try
  664.     to SPAWN after this.
  665.  
  666.  
  667. money #NUM                - Spawns #NUM dollar bills.
  668.  
  669.  
  670. move #??? [#1 #2 #3 ...    ]        ? Sets the value of #??? to
  671.                     #1, and #2, and #3,(?) or if they
  672.                     are not specified, to 0?
  673.  
  674.  
  675. operate                    ? Causes the current actor to
  676.                     push the 'operate' button thus
  677.     triggering a door, elevator or the like(?)
  678.  
  679.  
  680. palfrom #1 #2 #3            ? Rotates the palette from #1
  681.                     to #2 (and then back?), where #1
  682.     and 2 may be bitflags (aka 1, 2, 4, 8, etc...) where 16 specifies
  683.     red and 0 or 32 specifies green(?). #3 is a "delay" parameter that
  684.     controls how quickly the pallete change happens; larger values =
  685.     slower changes.(?) Ex. palfrom 16 16  // Screenflash red.
  686.  
  687.  
  688. pstomp                    ? Causes the player (which player?)
  689.                     to look down, and stomp the current
  690.     actor(?) Ex. "ifshrunk ifpdistl RETRIEVEDIST { pstomp killit }"
  691.  
  692.  
  693. quote #NUM                - Prints quote #NUM out on the
  694.                     screen in the usual fashion.
  695.  
  696.  
  697. resetactioncount            ? Resets the counter that counts the
  698.                     number of frames that have been
  699.     displayed by the action that the current actor is executing?
  700.  
  701.  
  702. resetcount                ? Resets the global count of
  703.                     number of frames displayed by
  704.     this actor since the last call to resetcount of ifcount(?)
  705.  
  706.  
  707. shadeto #NUM                ? ???
  708.  
  709.  
  710. shoot #WEAPON                ? Makes an enemy fire it's weapon.
  711.                     (Seems to be used to trigger blood-
  712.                     splattering, too)
  713.  
  714.  
  715. sizeto #1 #2                ? Scales the sprites associated
  716.                     with the current actor to 1/#1 (?)
  717.     in the X direction and 1/#2 in the Y direction.
  718.  
  719.  
  720. sound #SOUND                - Plays the sound associated with
  721.                     #SOUND by definesound at the current
  722.                     actor's location.
  723.  
  724.  
  725. soundonce #SOUND            ? ???
  726.  
  727.  
  728. spawn #ACTOR                - Spawns a copy of #ACTOR.
  729.  
  730.  
  731. spritepal #NUM                ? Changes the color of the current
  732.                     actor. Each value of #NUM corresponds
  733.     to a different color scheme, some(?) of which are:
  734.  
  735.         1 - bright blue
  736.         4 - dark
  737.         6 - Night vision green
  738.         7 - "messed up yellow"
  739.         8 - green
  740.         10 - somewhat red
  741.         19 - very reddish
  742.         22 - Almost normal.
  743.  
  744.  
  745. wackplayer                - Boot... TO THE HEAD!
  746.                     <Thwoosh-DONK!>
  747.  
  748.  
  749.  
  750. D. Examples
  751.  
  752.  * Trampoline Trash Cans
  753.  
  754.   I love those grey and red rubber-maid trash cans in the movie theater
  755. lobby in level 1. They're simple and static, so they're fun to play with.
  756. Let's make it so that when a player shoots one, it dents, and if they're
  757. stand too "close" when the trash can bounces back, the trash can will hit
  758. them and jar their viewpoint for a second.
  759.  
  760.   First of all, we have to understand the trash can actor code:
  761.  
  762.     action RUBCANDENT 1 1 1 1 1
  763.     action RUBCAN
  764.  
  765.     actor RUBBERCAN WEAK
  766.  
  767.       ifaction RUBCANDENT {
  768.         ifactioncount 16 {
  769.           strength 0
  770.           action RUBCAN
  771.           break
  772.         }
  773.       }
  774.  
  775.       else ifhitweapon {
  776.         ...
  777.           }
  778.  
  779.     enda
  780.  
  781.   Well, first of all, we don't care about what will happen to the trash can
  782. if it's hit with a weapon, so forget about the 'else ifhitweapon' part
  783. except to keep in mind that it takes care of denting the trash can for us.
  784. (Which is really just a call to 'action RUBCANDENT')
  785.  
  786.   Now then, before we start modifying things, try and think of what's
  787. happening from the trash can's perspective. This is Zen and the art of
  788. Duke3D: you must "become one" with your actor code. ;]
  789.  
  790.   Thinking this way, the important stuff in this actor could be paraphrased
  791. in english as: "if I'm dented, and if I've been dented for a while, pop back."
  792. We'd like to modify that to: "if I'm dented, and if I've been dented for a
  793. while, pop back. And if the player's "close," then bump them."
  794.  
  795.   So how do we tell if the player's close? We can use the "ifpdistl"
  796. primitive to tell if the player is less than a certain distance away.
  797. Now, how close is "close?" Apogee (in DEFS.CON) defined a certain
  798. distance to be close enough to retrieve an item. This is a good
  799. estimate of "close." Apogee called this distance RETRIEVEDISTANCE.
  800. How do we "bump" the player? Why, we "wackplayer," of course. ;]
  801.  
  802.   Okay, the code is shaping up. We have to modify the actor right
  803. in the part where the trash can bounces back. That's the stuff
  804. inside the 'ifactioncount 16 { ... }' Okay, so we go in there.
  805. What do we want? Well, IF player_close { bump_player }, right?
  806. So:
  807.  
  808.     actor RUBBERCAN WEAK
  809.  
  810.       ifaction RUBCANDENT {
  811.         ifactioncount 16 {
  812.           strength 0
  813.           action RUBCAN
  814.  
  815. /* We added these three lines below: */
  816.           ifpdistl RETRIEVEDISTANCE {    // If player's close...
  817.         wackplayer            // Boot... TO THE HEAD!
  818.           }
  819.  
  820.           break
  821.         }
  822.           }
  823.  
  824.       ...
  825.  
  826.     enda
  827.  
  828.  
  829.  
  830.  * Hollow-point bullets.
  831.  
  832.  * Kamikaze enemies.
  833.  
  834.  
  835.  
  836. E. So now what?
  837.  
  838.   Now go start playing with the .CON files. The worst that can happen
  839. is that DN3D will refuse to run because you made a mistake. (Forgot a
  840. brace, or something) If so, you'll have to correct the mistake or
  841. restore from your backup .CON file(s). (You DID make a backup, didn't
  842. you?  Of course you did.)
  843.  
  844.   Please do not email the author with questions; he probably doesn't know.
  845. Even if he does, he won't help you. If he starts answering requests, where
  846. will it all stop? ("How do I make the sound that Duke makes when he's
  847. ducking in the ooze sound like a fart and have bubbles float around and
  848. etc, etc...?") Also please don't e-mail Apogee or 3D Realms with questions;
  849. they have specifically disavowed all responsibility if you mess with the
  850. .CON files. Instead, do what comes naturally: play around until you figure
  851. out the answer.
  852.  
  853.  
  854.  
  855. F. Appendix
  856.  
  857.   * Where can I get this document?
  858.  
  859.   Several places. Here's a list:
  860.  
  861.     http://users1.ee.net/tgreco/confaq.htm
  862.     http://www.3drealms.com/confaq.html
  863.     http://rat.org/duke3d/faq.html
  864.     http://ccwf.cc.utexas.edu/~wieder/ROTT/extra.htm
  865.  
  866.  
  867.   * Contributors/Thank You's
  868.  
  869.    - Apogee Software/3D Realms for a truely fun game.
  870.    - Todd Greco, Joe Siegler, Rich Willoughby and Charlie Wiederhold for
  871. the HTML versions of the CFHG.
  872.    - Chris Gallagher (jazz411@aol.com), Rob Cannon (robbycan@gate.net),
  873. Mike Bobbit (Mike.Bobbitt@acadiau.ca), Peter Risser (PRISSER@us.ccl.com)
  874. for help with various primitives.
  875.